Shareware Grab Bag/Shareware Grab Bag.iso/007/d86v223.arc/MEMORY.DOC

Text File | 1987-04-08 | 17KB | 363 lines

---MEMORY.DOC---

Memory Display Windows

The debugger allows you to set up windows into your program
memory space. Using these windows, you can view memory in a
variety of formats.  The windows will remain in effect until you
cancel them; updating themselves automatically if the memory
changes.

A memory window line consists of a specification, typed in by
you, followed by a display, supplied by the debugger.

To type in a specification on any one of window lines 1 through
6, simply type the associated digit, 1 through 6, when the
debugger is in its main command-mode.  The cursor will jump to
the beginning of the memory-window line you are specifying.  You
then type in a display-format specification, followed by the
address of memory you want displayed.

The simplest form of the display-format specification is a single
letter, signifying one of the display types available.  The
choices are:

       B  for hexadecimal bytes
       W  for hexadecimal words
       N  for decimal bytes
       D  for decimal words
       Q  for octal bytes
       O  for octal words
       T  for text; each byte reduced to one ASCII display-
             character
       A  for ASCII text, each byte occupying 2 display-
             characters
       C  for ASCII characters, occupying 2 bytes if needed,
             otherwise one

A format-specification of one of the above letters will cause the
debugger to display the array of bytes starting at the address
you specify, in the format indicated by the letter, as long as
there is room on the line. All letters in a format-specification
(or in any other context in the debugger) can be typed in either
upper- or lower-case.

The format-specification should be terminated by a comma.  After
the comma (and an optional space), you type the address of memory
you want displayed. This consists of two values, the segment
followed by the offset.  The values should be separated by a
comma. You can omit the segment value if you wish: in that case,
the current value of DS is used. The debugger reminds you that
you have specified this option by following what you type with 2
commas instead of one.

The value you type can take one of the following forms:
   a. a numeric constant, whose format is just as in the assembly
      language (leading zero means default hex, otherwise default
      decimal)
   b. a register name (IP is now accepted as a register name)
   c. a user-symbol from the assembly-language program being
      debugged.

After you type the address-specification, you hit the ENTER key,
and the debugger fills out the rest of the line with the memory
display.

For example, if you want to display hex bytes starting at 01000
hex on display-line 2, you type 2b,01000<ENTER>. The cursor jumps
to the line immediately when you type the 2, and it displays the
b,01000 on the line as you type it.  The b says you want hex
bytes, and the 01000 has a leading zero to signify a hexadecimal
address, not decimal.  When you press the ENTER key, the debugger
displays two commas, followed by the hex bytes.  If the memory is
zeroed, you will see 00 00 00 00 00 etc. to the end of the
display-line.


Erasing Memory Display Lines

Any memory-display window that you specify will remain in effect,
always updated to show the latest memory contents, until you
explicitly erase it. To erase a window, you type the number of
the window, followed by either a blank or the ENTER key.  The
line will also be erased if you start typing a format-
specification, and you hit the ENTER key before you get to your
address-specification.

In the coming sections, many of the examples assume (and they say
so) that your display is blank before you type in the example.
You can always get a blank display by typing in each number
followed by a blank: "1 2 3 4 5 6 ".


Continuation Lines

You may continue a memory-display window onto the next line, by
placing a double-quote mark " at the beginning of the next line.
You may do this in one of two ways: you may type the number of
the next line, followed by the double-quote mark; or you may
simply type the double-quote mark at the command level.  The
first method allows you to specify which window-line you want
continued, if there is more than one.  The second method is more
convenient to use.  It places the quote-mark on the last blank-
line that immediately follows a non-blank line.

You may continue placing "-marks on as many lines as you have,
creating a multi-line display.

The debugger follows the "-mark with the address of memory being
displayed, followed by the memory, according to the start of the
type-specification of the line being continued.  The memory
display is aligned with the display of above line.

If you are creating a multi-line display, and your specification
is a long one, you may wish to start the display at the beginning
of the next line, rather than after the specification on the
first line.  This will often give you more room.  You do this by
terminating the format-specification with a slash / instead of a
comma.  For example, to display many hex bytes at the array
BYTE_ARRAY, type 1b/byte_array<ENTER>""""" when the memory-
display is empty.


Mixed Format Specification

Instead of having all your bytes or words on a line displayed in
the same format, you can mix your formats.  You do this by
providing more than one letter in your format-specification.  The
debugger will display one memory unit for each letter-type you
specify.  The line will be filled out with the last type given.
For example, if you type 3nwb,01000<ENTER>, you will get a
display on memory-line 3 of the decimal byte at 01000, the hex
word at 01001, and an array of hex bytes starting at 01003.


Numbers in a Format Specification

You may precede any letter in a format specification with a
number up to 255. The effect is the same as if you had repeated
the letter the given number of times.  For example, if you type 1
to go to memory line 1, followed by 4w10tb,02000<ENTER>, you will
get 4 hex words at 02000, 10 text characters at 02008, and an
array of hex bytes from 02012 filling out the rest of the line.

You may also end your format specification with a number up to
255.  This will cause the entire specification to be repeated the
given number of times. If there is room on the line for the full
number given, the display will stop there-- there will be no
repeating of the last type-byte.  If there is not room on the
line for the full number of global iterations, the debugger will
stop at the end of the last iteration that would fit.  For
example, the specification b8 causes 8 hex bytes to be displayed,
and the remainder of the display line to be blank.  The
specification b3w9 will cause the debugger to try to output 9
records, each consisting of a hex byte followed by 3 hex words.
After putting out 2 such records, the debugger will see that
there is not room for a third full record, so it will stop.  This
stopping at the record-boundary allows you to continue the
display, with correct alignment, on subsequent lines.


Spacing Between Memory-Display Units

In general, the debugger provides a space between each unit (byte
or word) it displays.  There is an exception, however: the
debugger will not space between adjacent text-characters (A,C, or
T specifications).

There are special specifiers G, J, and M, described in the
section below, that allow you to override the debugger's spacing
policies.


Special-Action Format Specifiers

In addition to the nine letters mentioned above, that specify
data types, there are 7 other letters, and 2 other characters,
that cause the debugger to perform special actions.  Following is
a complete description all 18 non-digit characters that can occur
within a format specification:

=  causes a display, using the format of the letter following =,
   of the current memory pointer value, instead of the contents
   of the memory location.  If a letter does not follow the =,
   then W is used; i.e., the pointer is display as a 4-digit hex
   word.  There are two uses for this feature that come to mind:

   * If your address specification is symbolic, you can display
     the equivalent numeric address with =w, telling you exactly
     where the symbol is in memory.  Note that this display
     implicitly occurs at the beginning of continuation lines.
     If the format-specification begins with =, then the implicit
     display is suppressed, because the same address is given
     explicitly by the L.

   * You can display the values of registers in a format other
     than hex.  For example, in the 8086 debugger you can display
     AX as a decimal number by specifying =d1,ax on one of the
     memory-display lines.

@  causes the debugger to read the next byte it was going to
   display, and instead of displaying the byte, use it as a
   count, to repeat the next letter in the specification.  The
   debugger uses only the bottom 7 bits of the memory byte for
   the count.  For example, of the memory contains a length byte
   followed by that number of text characters, the text could be
   displayed by specifying @t (or @a or @c, depending on what you
   want the display to look like).  If the memory contains 05 41
   42 43 44 45, the @t would cause ABCDE to be displayed.

A  causes a display of a single ASCII byte, always using 2
   display bytes. The following table shows what is displayed for
   unusual bytes:

    range of N         display of N               Example
    ----------         ------------               -------
     00--1F            ^ followed by N+040         02 is ^B
     22                ""
     23                "#
     24                "$
     5E                "^
     7F                ^r  (r stands for rubout)
     80--9F            $ followed by N-080+040     081 is $A
     A0--FE            # followed by N-080         0B1 is #1
     FF                $r

   All other bytes cause a display of a space following by the
   appropriate ASCII byte.  The A specification is used when you
   need guaranteed display length for proper alignment of
   continuation lines; and you do not want the potential loss of
   information provided by the single-byte T specification.

B  causes a display of a single byte as a 2-digit hexadecimal
   number.  Numbers less than hex 10 have a leading 0, so that
   the display is always 2 digits.

C  causes a display of a single ASCII character, just as the A
   specification, except that normal characters (not in the
   table) display as just one byte, without the preceding space.

D  causes the display of a 16-bit word as an unsigned positive
   decimal number. There will be no leading zeros in the display;
   so the length of the display depends on the size of the
   number.

G  causes a gap between the adjacent display-formats, of one
   space more than there would have been without the G.  For
   adjacent string bytes, this means a space where there would
   have been none.  For other data types, this means two spaces
   where there would have been one.

J  (join) causes two adjacent data types, that would have had a
   space between them, to have no space.

L  (line) causes the display of an entire text line, using the C-
   format for each character of the line.  The debugger does not
   display the terminating carriage return; nor does it display
   the following linefeed if there is one.  (If you want it to,
   specify LRC or LRRCC instead of L.) If a carriage return is
   not found and the display line fills, then the L-specifier is
   cut off in mid-string.  Any continuation line would start up
   at the beginning of the format specification, at the mid-
   string place in memory.

M  (mark) causes a vertical-bars output to be made.  The output
   will replace a separating space that would have been output in
   the position.  If you want the space, you can provide G on
   either side (or both sides) of the M.

N  (number) causes the display of an 8-bit byte as an unsigned
   positive decimal number.  There will be no leading zeroes in
   the display; so the length of the display depends on the size
   of the number.

O  causes a display of a 16-bit word as a 6-digit octal number.
   Numbers less than octal 100000 have one or more leading
   zeroes, so that the display is always 6 digits.

Q  causes a display of a single byte as a 3-digit octal number.
   Numbers less than octal 100 have one or more leading zeroes,
   so that the display is always 3 digits.

S  causes the display of an entire null-terminated string, using
   the C-format for each character of the string.  The
   terminating null (hex 00) does not generate a display (if you
   want it to, specify SRC instead of S).  If a null is not found
   and the display line fills, then the S-specifier is cut off in
   mid-string.  Any continuation line would start up at the
   beginning of the format specification, at the mid-string place
   in memory.

T  causes the display of a single ASCII text byte, with a
   guaranteed display-space of one character.  The character
   displayed is the same as the second character of the A-format.
   This means that you will not be able to tell the difference
   between normal, displaying ASCII characters, and their control
   and non-ASCII counterparts.  You gain a compact
   representation, but you also gain ambiguity.

U  (unskip) causes the memory display pointer to decrement by one
   byte.   No display is generated by this command.  This command
   is useful in several contexts:

   * displaying memory in more than one format.  For example, the
     specification 8b8r2g8a gives a hex-and-ASCII side-by-side
     display, similar to that provided by many memory-dump
     programs.

   * displaying memory out of its sequence order.  To test your
     understanding of the special-action letters in a format
     specification, you should convince yourself that the
     specification xb2rjbx99/ gives the same display on the
     following "-continuation line as the specification w/ does.

   * displaying the count-byte consumed by the @ character.  For
     example, instead of @t, you could specify nr@t, which would
     display the string count as well as the string.  If memory
     were 05 41 42 43 44 45, this would be 5 ABCDE.

W  causes a display of a 16-bit word as a 4-digit hex number.
   Numbers less than hex 1000 have one or more leading zeroes, so
   that the display is always 4 digits.

X  causes the debugger to skip over the memory byte currently
   pointed to, without displaying it.  The memory pointer is thus
   incremented.

Z  is given immediately following another format letter.  It
   causes the display to fill out the line with displays of the
   given preceding format; but instead of starting with the given
   address, the debugger starts with a lower address, and
   displays memory up to but not including the given address.

   The most common usage of Z is to display the memory just
   output by a moving output pointer.  For example, in the 8086
   debugger, you could specify bz,es,di to display the hex bytes
   most recently output by the STOSB instruction.

   Note that Z makes sense only in a limited number of contexts.
   You will almost certainly want to use Z only as the second
   letter of a two-letter specification, as in the example above.
   We further recommend that a format-letter that generates a
   fixed-length display be used; i.e., B,W,Q,O,T, or C.  If you
   use a variable-length display (N,D, or A), the debugger will
   be as pessimistic as possible about the number of display
   characters needed, so that the display will likely terminate
   before the end of the line.

   A continuation of a Z-line will produce the same output as the
   original line.  If you want to continue beyond the address
   given, repeat the specification without the Z.

   We now discuss what happens if you use Z in other contexts.
   Unless your taste runs to the bizarre, you should skip this
   paragraph.  Since Z fills out a line, there should be no
   specifiers after Z: they would be ignored.  Also note that Z
   has an effect only on the single letter that precedes it.  If
   you precede Z with more than one letter, you will get a
   confusing effect: the display would start out forward from the
   address, then it would retreat when it got to Z's preceding
   letter.  The Z-array would run up to the address reached
   before, which is forward from the address you specified.